[Spring] RESTDocs로 API 명세서 만들기

plugins {
	id "org.asciidoctor.jvm.convert" version "3.3.2" // AsciiDoc 파일을 변환하고 Build 폴더에 복사하기 위해 Asciidoctor 플러그인 적용
}

configurations {    // Asciidoctor를 확장하는 asciidoctorExt에 대한 종속성 구성을 선언한다.
	asciidoctorExt
}

dependencies {
  // asciidoctorExt에 spring-restdocs-assciidoctor 의존성을 추가한다.
	// 이 종속성이 있어야 build/generated-snippets에 생긴 스니펫 조각(.adoc)들을 프로젝트 내의 .adoc 파일에서 읽어들이고 html 파일로 변환할 수 있게해준다.(operation 블록 매크로 사용 가능)
  // 이렇게 하면 우리 프로젝트의 `.adoc` 파일에서 사용될 속성이 build/generated-snippets 밑에 생성된 Snippet를 가리키도록 자동으로 정의됨.
	asciidoctorExt 'org.springframework.restdocs:spring-restdocs-asciidoctor'
	testImplementation 'org.springframework.restdocs:spring-restdocs-restassured' // RestAssured를 사용하기 위한 의존성 추가
}

ext { // 변수를 선언하는 것이라고 보면 됨
  // 스니펫 파일들이 생성될 디렉토리를 정의한다.
	snippetsDir = file('build/generated-snippets')
}

test {
    // snippetsDir를 test task의 출력으로 설정한다.=>test 결과물(스니펫)들이 build/generated-snippets 경로에 생성된다.
	outputs.dir snippetsDir
	useJUnitPlatform()
}

asciidoctor { // asciidoctor task(gradle)을 정의한다.
	configurations 'asciidoctorExt' // 앞서 작성한 asciidoctorExt 설정을 사용하도록 함.
	baseDirFollowsSourceFile() // 특정 .adoc에 다른 adoc 파일을 가져와서(include) 사용하고 싶을 경우 경로를 baseDir로 맞춰주는 설정이다.
													     // 개별 adoc으로 운영한다면 필요 없는 옵션이다.
	inputs.dir snippetsDir // snippetsDir 를 asciidoctor task의 input으로 지정한다.(스니펫을 불러들일 경로)
	dependsOn test // 문서 생성 전 테스트가 실행되도록 test에 종속성 설정
}

asciidoctor.doFirst { //asciidoctor을 처음 시작할 때 실행되는 task
    delete file('src/main/resources/static/docs') // static/docs 폴더 비우기
}

// gradle task 정의
// asccidoctor 작업 이후 생성된 HTML 파일(index.html)을 static/docs로 copy한다.
task copyDocument(type: Copy) {
    dependsOn asciidoctor // asciidoctor 테스크 이후에 실행되도록 설정함.

    from file("build/docs/asciidoc")   // build/asciidoc/에 존재하는 html 파일을 src/main/resources/static/docs 경로로 복사한다.
    into file("src/main/resources/static/docs") // 우리 버전관리 시스템에 포함시킬거니까 여기로 복사.
}

build {
    dependsOn copyDocument // copyDocument 테스크 이후에 실행되도록 설정함.
}

bootJar {    // 빌드 후 생성된 문서(html)를 jar 파일에 패키징한다.
	dependsOn copyDocument // 빌드 전 문서가 copyDocument task가 먼저 실행되도록 한다.
	from ("${asciidoctor.outputDir}/html5") { // 생성된 문서를 스프링 어플리케이션에서 보여주기 위해 static/docs 경로에 복사한다.
		into 'static/docs'
	}
}

@ExtendWith({RestDocumentationExtension.class, SpringExtension.class})
public class JUnit5ExampleTests {

private RequestSpecification spec; //테스트에서 사용할 명세 스펙

		@BeforeEach
		void setUp(RestDocumentationContextProvider restDocumentation) {
			this.spec = new RequestSpecBuilder()
          .addFilter(documentationConfiguration(restDocumentation))
					.build();
		}

@ExtendWith({RestDocumentationExtension.class, SpringExtension.class})
public class JUnit5ExampleTests {

    private RequestSpecification spec; //테스트에서 사용할 명세 스펙

		@BeforeEach
		void setUp(RestDocumentationContextProvider restDocumentation) {
			this.spec = new RequestSpecBuilder()
          .addFilter(documentationConfiguration(restDocumentation))
					.build();
		}
		...
}

// get product
RestDocumentationFilter restDocumentationFilter = document(
						"get-product",    // identifier로, adoc 파일을 저장할 디렉토리의 이름이 된다.
		        pathParameters(
		            parameterWithName("productId").description("확인할 상품 id")
            ),
            responseFields(
                fieldWithPath("id").description("상품 id"),
                fieldWithPath("name").description("상품명"),
                fieldWithPath("price").description("상품 가격"),
                fieldWithPath("imageUrl").description("상품 이미지 주소")
            )
        );

RequestSpecification given =given(this.spec).filter(restDocumentationFilter);

var responseProduct = given.when()
    .get("/products/{productId}", productId)
    .then()
    .statusCode(HttpStatus.OK.value())
    .extract()
    .jsonPath()
    .getObject(".", ProductResponse.class);
...

task copyDocument(type: Copy) {
    dependsOn asciidoctor

    from file("build/docs/asciidoc")
    into file("src/main/resources/static/docs")
}